SDK (Software Development Kit) is a set of tools for developing custom applications. Wialon SDK includes several APIs. The most basic of them is the Remote API, and these articles are focused on studying this exact tool. Remote API allows access to data through HTTP requests and is relevant for 1C, PHP, C++/C#, and other programming languages. JS API and others are built on top of the Remote API.

This article will cover the basic knowledge necessary for beginners to use Remote API.

Viewing Requests in the Browser

When starting to explore the SDK, it is often necessary to understand which API request is being sent to the server when performing a certain action in the Wialon interface. This can be easily tracked using built-in browser tools for network request monitoring.

In Chrome browser, you can do it using the Network tab in the Developer Tools, which can be opened by pressing F12. In other browsers, this tool may open differently, as described in the browser's documentation.

When viewing network requests, you can see the sent request, its parameters, and the response from the API server in JSON format.

Request Format

HTTP requests are sent to the server in the following format:

https://host/wialon/ajax.html?svc=REQUEST_NAME¶ms={PARAMETERS}&sid=SESSION_IDENTIFIER

Obtaining a Token and Authorization

Wialon uses a token for authorization, which is a key used for encrypted user identification.

To create a token, you can use the oAuth form. After you log in successfully, the token will be displayed in the browser's address bar as the value of the access_token parameter. It is important here to consider additional parameters that regulate properties such as token duration (duration parameter), user name (user parameter), token flags (access_type parameter), and others.

Example of an extended form for obtaining a token:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

Example of a response:

https://hosting.wialon.com/login.html?lang=en&user=USER_NAME&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=TOKEN_VALUE&svc_error=0

After obtaining the token, you can use it for authorization. Here is the example of logging in with a token:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"TOKEN_VALUE"}

The response to the token login contains the eid parameter, and its value is the unique session identifier. It will be used in almost all API requests.

Setting the Time Zone

By default, when working with the Remote API, data is displayed according to the GMT+0 time zone. To change it to the desired time zone, the render/set_locale request is used. It is sufficient to execute this request within one active session.

When sending the render/set_locale request, you must use the tzOffset parameter. The standard method for calculating its value is described in the documentation.

You can also find out the required value of the tzOffset parameter by viewing network requests while changing the user's time zone in the web interface.

System ID

In the API, work with almost every item is done through system IDs, which are represented by unique numerical values.

System IDs are not displayed in web interfaces by default but they can be seen in three ways:

1. In the response to a request for searching items by property (core/search_items). We will explain it in more detail in the next section of this article.
   
2. In the parameters of requests when viewing network requests in the browser.

3. In the avl_id column in the management system.

   To make the avl_id column shown, you need to log in to the CMS and add ?features=avl_id to the end of the link. An example of such a link is shown in the image below.
   
   

Search Items by Property

This request allows you to find items by certain properties.

The search is performed for the following types of items, which are specified in the itemsType field:

• avl_hw — hardware type;
  
• avl_resource — resource;
  
• avl_retranslator — retranslator;
  
• avl_unit — unit;
  
• avl_unit_group — unit group;
  
• user — user;
  
• avl_route — route.
  

One of the possible search properties can be subitems. In this case, the propType parameter is set to propitemname, and the propName parameter takes the following values:

• units:
  
  • unit_sensors — sensors;
  • unit_commands — commands;
  • service_intervals — service intervals;
    
    
• resources:
  
  • drivers — drivers;
  • driver_groups — driver groups;
  • jobs — jobs;
  • notifications — notifications;
  • trailers — trailers;
  • trailer_groups — trailer groups;
  • zones_library — geofences;
  • reporttemplates — report templates;
  • orders — orders;
    
    
• routes:
  
  • rounds — rounds;
  • route_schedules — schedules;
    
    
• retranslators:
  
  • retranslator_units — retranslator units;
    
    
• units, users, or resources:
  
  • custom_fields — custom fields;
  • admin_fields — administrative fields.

The information in the response depends on the flags specified in the search request in the flags parameter. Flags are specified in DEC format.

Let's consider several examples of using the request for searching items by property (other examples can be found in the documentation).

Search Items by a Specific Name

In case you need to get a list of all units available to the user with the word Tractor in their name, as well as information about the sensors created in these units, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Search Users Created after a Specific Date

Imagine you need to get a list of users created after February 23, 2021, 05:41:46 (GMT+0). The response should contain user's system IDs and email addresses.

In such a case use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units of a Specific Type

Let’s get a list of units with the Wialon Retranslator hardware type that have sent messages after February 12, 2023, 12:00:00 (GMT+0). The response must display information about the sensors on the units, the last message date, and the position. In this case, use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units by Sensor Name

To get a list of units that have a sensor named Engine created, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Unit Groups by Multiple Properties

To get a list of unit groups created by User and containing more than 5 units, the following request can be used:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=SESSION_IDENTIFIER

List of Common Errors

An error is displayed when it is not possible to execute a request. A complete list of returned errors can be found in the documentation.

The most common errors are the following:

• {error: 1} — invalid session.
  This error is displayed when the unique session identifier has expired. To fix this error, simply log in with the token again and use the new session identifier (sid) for further requests.

  If within 5 minutes no request is made within the session, then it becomes inactive. To keep the session active, you can send an avl_evts request every 5 minutes.

• {error: 4} — invalid input.
  This error is displayed if there is a mistake in the request text, for example, not all required parameters are specified, text parameters are not enclosed in quotes, there is no opening or closing bracket, etc. To fix this error, correct the text of the executed request according to its description in the documentation.
  
  
• {error: 7} — access denied.
  This error is displayed if the user does not have sufficient access flags to execute the request. To fix this error, check if the token used to obtain the unique session identifier has sufficient access flags, as well as if the user the token was generated for has sufficient access rights regarding the used items.
  

Ekaterina Grib,Customer Service Engineer 2023-08-02

In this article, we will cover the creation of accounts and units using the Remote API. These objects are essential when working with Wialon, and their creation requires a chain of mandatory actions.

Creating an Account

Before performing this action, it is necessary to remember two important terms:

• Creator — this is the user of the system on whose behalf this object was created.
  
• Account — this is a macro-object of the system, which represents the unity of a resource, a user, and a billing plan.

Based on this, to create an account, you need to:

1. Find a suitable billing plan.
2. Find the system ID of the user-creator which will relate to the future account creator.
   
3. Create a new user on behalf of the found user-creator.
   
4. Create a resource on behalf of the new user.
5. Merge the new user, resource, and billing plan into an account.

Let's consider the requests that will be needed at each of these steps, using the following example: it is necessary to create an account with the name sdk_account, which will be located under the account of the user manager in the service hierarchy.

1. Searching a Billing Plan

Use the request core/get_account_data.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/get_account_data¶ms={"type":1}&sid=SESSION_IDENTIFIER

The names of assigned billing plans will be displayed in the response to the request in the subPlans parameter. Let's assume that we will use a billing plan with the name standard_client.

2. Searching the System ID of the User-creator

Use the request core/search_items.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"sys_name","propValueMask":"manager","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

The system ID of the user-creator will be displayed in the response to the request in the id parameter. Let's assume it has a value of 11111.

3. Creating a New User

Use the request core/create_user.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_user¶ms={"creatorId":11111,"name":"sdk_account","password":"Pa%24%24w0rd","dataFlags":1}&sid=SESSION_IDENTIFIER

The system ID of the new user will be displayed in the response to this request under the id parameter. Let's assume it has a value of 22222.

4. Creating a Resource

Use the request core/create_resource.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_resource¶ms={"creatorId":22222,"name":"sdk_account","dataFlags":1,"skipCreatorCheck":0}&sid=SESSION_IDENTIFIER

The system ID of the new resource will be displayed in the response to this request under the id parameter. Let's assume it has a value of 33333.

5. Account Merging

Use the request account/create_account.

https://hst-api.wialon.com/wialon/ajax.html?svc=account/create_account¶ms={"itemId":33333,"plan":"standard_client"}&sid=SESSION_IDENTIFIER

Creating a Unit

To create a unit using the Remote API, you need to:

1. Find the system ID of the hardware type.
2. Find the system ID of the user-creator, in whose account the future unit will be located.
   
3. Create a unit.
   
4. Assign a unique ID to the unit.

Let's consider the necessary requests using the following example: it is necessary to create a unit Delivery truck with the hardware type Wialon IPS and a unique ID 12345 in the account of the user sdk_account.

1. Searching the System ID of the Hardware Type

Use the request core/get_hw_types.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/get_hw_types¶ms={"filterType":"name","filterValue":["Wialon%20IPS"],"includeType":0,"ignoreRename":1}&sid=SESSION_IDENTIFIER

The system ID of the hardware type will be displayed in the response to the request in the id parameter. Let's assume it has a value of 44444.

2. Searching the System ID of the User-creator

Use the request core/search_items.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"sys_name","propValueMask":"sdk_account","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

The system ID of the user-creator will be displayed in the response to the request in the id parameter. Let's assume it has a value of 22222.

3. Creating a Unit

Use the request core/create_unit.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_unit¶ms={"creatorId":22222,"name":"Delivery%20truck","hwTypeId":"44444","dataFlags":1}&sid=SESSION_IDENTIFIER

The system ID of the unit will be displayed in the response to the request in the id parameter. Let's assume it has a value of 55555.

4. Assigning a Unique ID

Use the request unit/update_device_type.

https://hst-api.wialon.com/wialon/ajax.html?svc=unit/update_device_type¶ms={"itemId":55555,"deviceTypeId":"44444","uniqueId":"12345"}&sid=SESSION_IDENTIFIER

Ekaterina Grib,Customer Service Engineer 2023-08-20

In this article, we will cover working with report templates using the Remote API. Executing reports through the SDK implies a sequence of mandatory actions that are not visible when working in the web interface. To complete the picture, examples of working with reports with and without grouping will be given.

Creating Reports

In most cases, users create report templates in the web interface and then execute them using API requests. We will be considering such cases later in this article.

However, you can create a report template through the SDK by using the request report/update_report.

Sequence of Actions

To obtain report results using the Remote API, several consecutive requests need to be sent. The use of some of them depends on the presence of grouping in the report and the amount of analyzed data. Here is the general list of actions:

1. Authorization through the request token/login and setting localization through the request render/set_locale.
   
   

2. Obtaining the necessary system IDs for:
   

   • the object the report needs to be executed for;

     Since reports can be executed for drivers, trailers, passengers, geozones, and their groups, in some cases it will also be necessary to obtain system IDs for these subitems.

   • the resource that contains the report template;
     
   • the report template itself.
     
     

3. Executing the report through the request report/exec_report.

   In general, we recommend executing the report in the background mode on the server. Despite the increase in the number of steps, this can be useful if the report takes a long time to execute due to a large number of objects, report execution interval, number of tables and charts, etc. Later in this article, we will specifically consider executing the report in the background mode.
   
   If the report is not executed in the background mode on the server, then the response to this request will be similar to the response from step 5, so you can proceed directly to step 6.
   

4. Checking the report execution status through the request report/get_report_status.
   After confirming the report is ready, you can proceed with following the instructions.
   
   
5. Obtaining the report result through the request report/apply_report_result.
   The result of this request will provide the number of rows, columns, and levels of nesting if grouping is used.
   
   
6. Getting the table rows through the request report/get_result_rows for a report without grouping or through the request report/select_result_rows for a report with grouping.
   The selection of the table, nesting levels, and displayed rows is based on the data from the previous response.
   
   
7. Exporting to a file through the request report/export_result.
   This step is optional but quite simple and useful, so we will also consider it.
   
   
8. Deleting the result of the previous report through the request report/cleanup_result.
   This step is mandatory if multiple reports must be executed in one session.

Next, we will consider two examples of working with reports (without grouping and with grouping).

Working with a Report without Grouping

Let’s imagine, it we need to obtain the results of the the report List of trips, available to the user authorized by a token, for the unit Truck 0769 (system ID 55555) for the time interval from 2023 June 30 20:00 to 2023 July 01 03:59 (GMT+0) and export it to a PDF file using API requests.

In the web interface, the result looks as follows:

1. Authorization and Localization

Use the request token/login.

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"TOKEN_VALUE"}

Authorization details are described in one of the previous articles.

Localization settings include setting the time zone (which has also been discussed earlier), date format, and other parameters.

Use the request render/set_locale.

https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"en","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=SESSION_IDENTIFIER

2. Obtaining System IDs

In one of the previous articles, we have already described how to search items by property, so now we will focus only on searching a resource and report template.

Let’s get a list of all resources that have a report template named List of trips available to the user authorized by a token. Use the request core/search_items:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"List%20of%20trips","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_resource",
		"propName":"reporttemplates",
		"propValueMask":"List of trips",
		"sortType":"sys_name",
		propType:"propitemname",
		or_logic:"0"
		},
	"dataFlags":8193,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"sdk_account",
			"cls":3,
			"id":12345678,
			"mu":0,
			"rep":{
				1:{
					"id":1,
					"n":"List of trips",
					"ct":"avl_unit",
					"c":59352
				},
				2:{
					"id":2,
					"n":"Grouped trips",
					"ct":"avl_unit",
					"c":6883
				}
			},
			"repmax":-1,
			"uacl":-1
		}
	]
}

Pay attention to the following parameters in the response:

• nm — resource name;

• rep — an array of report templates created in the resource;

  If this parameter is displayed as empty, it means that there are no report templates created in the resource.

• n — subitem name;
• id — system ID.

In this case, the user has access to the sdk_account resource with system ID 12345678, which contains the report template List of trips with system ID 1.

3. Executing the Report

Use the request report/exec_report.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":1,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=SESSION_IDENTIFIER

{
	"remoteExec":1
}

4. Checking the Execution Status

Since the report is being executed in the background on the server, we will check its execution status using the request report/get_report_status.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=SESSION_IDENTIFIER

{
	"status":4
}

A status code 4 means that the report has been executed successfully. The interpretation of other values can be found on the page with a request description.

5. Obtaining the Report Result

Use the request report/apply_report_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=SESSION_IDENTIFIER

{
	"reportResult":{
		"msgsRendered":0,
		"stats":[],
		"tables":[
			{
				"name":"unit_trips",
				"label":"Trips",
				"grouping":{},
				"flags":4224,
				"rows":4,
				"level":1,
				"columns":5,
				"header":[
					"№",
					"Beginning",
					"End",
					"Duration",
					"Mileage"
				],
				"header_type":[
					"",
					"time_begin",
					"time_end",
					"duration",
					"mileage"
				]
			}
		],
		"attachments":[]
	}
}

Three key parameters from the response that are important for us here are as follows:

• tables — shows the number of tables in the report as an array. In this case, only one table (Trips) is mentioned, therefore its index will be 0.
• rows — the number of rows in the table, which is 4 in this case. Therefore, their indexes range from 0 to 3.
• level — the number of levels of nesting, which is 1 in this case, as there is no grouping in the report.

Other parameters from the response can also be briefly listed. The columns parameter indicates the number of columns, and their names are described in the header parameter. A value of 0 for the msgsRendered parameter indicates that the report template doesn't display tracks on the map. Empty stats and attachments parameters indicate that there are no Statistics nor attachments (e.g., charts) in the report template.

6. Getting Table Rows

Knowing the index of the table content, let's display it using the request report/get_result_rows.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_result_rows¶ms={"tableIndex":0,"indexFrom":0,"indexTo":3}&sid=SESSION_IDENTIFIER

[
	{
		"n":0,
		"i1":0,
		"i2":790,
		"t1":1688144420,
		"t2":1688154878,
		"d":0,
		"c":[
			"1",
			{
				"t":"2023-06-30 20:00:20",
				"v":1688144420,
				"y":47.2941741943,
				"x":26.4906959534,
				"u":55555
			},
			{
				"t":"2023-06-30 22:54:38",
				"v":1688154878,
				"y":43.8697662354,
				"x":26.0177116394,
				"u":55555
			},
			"2:54:18",
			"469.54 km"
		]
	},
	{
		"n":1,
		"i1":936,
		"i2":2171,
		"t1":1688155181,
		"t2":1688169690,
		"d":0,
		"c":[
			"2",
			{
				"t":"2023-06-30 22:59:41",
				"v":1688155181,
				"y":43.8698196411,
				"x":26.0177154541,
				"u":55555
			},
			{
				"t":"2023-07-01 03:01:30",
				"v":1688169690,
				"y":41.7139854431,
				"x":26.3660545349,
				"u":55555
			},
			"4:01:49",
			"343.84 km"
		]
	},
	{
		"n":2,
		"i1":2340,
		"i2":2486,
		"t1":1688170034,
		"t2":1688170841,
		"d":0,
		"c":[
			"3",
			{
				"t":"2023-07-01 03:07:14",
				"v":1688170034,
				"y":41.7140579224,
				"x":26.365901947,
				"u":55555
			},
			{
				"t":"2023-05-01 09:23:10",
				"v":1688170841,
				"y":41.7122383118,
				"x":26.3712425232,
				"u":55555
			},
			"0:13:27",
			"1.39 km"
		]
	},
	{
		"n":3,
		"i1":2833,
		"i2":2910,
		"t1":1688171565,
		"t2":1688173175,
		"d":0,
		"c":[
			"4",
			{
				"t":"2023-07-01 03:32:45",
				"v":1688171565,
				"y":41.7120819092,
				"x":26.3711204529,
				"u":55555
			},
			{
				"t":"2023-07-01 03:59:35",
				"v":1688173175,
				"y":41.5760040283,
				"x":26.9871864319,
				"u":55555
			},
			"0:26:50",
			"57.84 km"
		]
	}
]

7. Export to File

Let’s export the result to a PDF file using the request report/export_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"List%20of%20trips"}&sid=SESSION_IDENTIFIER

There is no response displayed for this API request, instead, the file download starts automatically.

8. Deleting the Result of the Previous Report

Use the request report/cleanup_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=SESSION_IDENTIFIER

{
	"error":0
}

A zero value indicates successful deletion.

Working with a Report with Grouping

Now we need to obtain the results of the report Grouped trips, available to the user authorized by a token, for the unit Truck 0769 (system ID 55555) for the time interval from 2023 June 30 20:00 to 2023 July 01 03:59 (GMT+0) and export it to a PDF file using API requests.

In the web interface, the result looks as follows:

Based on the result in the web interface, you can see that the Trips table has grouping by months and dates, meaning the report has 3 levels of nesting:

• The first level contains rows with months.
  The second level contains rows with dates within the month.
• The third level contains rows with trips within the date.

1. Authorization and Localization

Use the request token/login.

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"TOKEN_VALUE"}

Authorization details are described in one of the previous articles.

Localization settings include setting the time zone (which has also been discussed earlier), date format, and other parameters.

Use the request render/set_locale.

https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"en","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=SESSION_IDENTIFIER

2. Obtaining System IDs

In one of the previous articles, we have already described how to search items by property, so now we will focus only on searching a resource and report template.

Let’s get a list of all resources that have a report template named Grouped trips available to the user authorized by a token. Use the request core/search_items:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"Grouped%20trips","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_resource",
		"propName":"reporttemplates",
		"propValueMask":"Grouped trips",
		"sortType":"sys_name",
		propType:"propitemname",
		or_logic:"0"
		},
	"dataFlags":8193,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"sdk_account",
			"cls":3,
			"id":12345678,
			"mu":0,
			"rep":{
				1:{
					"id":1,
					"n":"List of trips",
					"ct":"avl_unit",
					"c":59352
				},
				2:{
					"id":2,
					"n":"Grouped trips",
					"ct":"avl_unit",
					"c":6883
				}
			},
			"repmax":-1,
			"uacl":-1
		}
	]
}

Pay attention to the following parameters from the response:

• nm — resource name;

• rep — an array of report templates created in the resource;

  If this parameter is displayed as empty, it means that no report templates are created in the resource.

• n — subitem name;
• id — system ID.

In this case, the user has access to the sdk_account resource with system ID 12345678, which contains the report template Grouped trips with system ID 2.

3. Executing the Report

Use the request report/exec_report.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":2,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=SESSION_IDENTIFIER

{
	"remoteExec":1
}

4. Checking the Execution Status

Since the report is being executed in the background on the server, let’s check the status of its execution using the request report/get_report_status.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=SESSION_IDENTIFIER

{
	"status":4
}

Status code 4 indicates that the report has been executed successfully. The interpretation of other values can be found on the page with a request description.

5. Obtaining the Report Result

Use the request report/apply_report_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=SESSION_IDENTIFIER

{
	"reportResult":{
		"msgsRendered":0,
		"stats":[],
		"tables":[
			{
				"name":"unit_trips",
				"label":"Trips",
				"grouping":{
					"nested":{
						"type":"day"
					},
					"type":"month"
				},
				"flags":4491,
				"rows":2,
				"level":3,
				"columns":6,
				"header":[
					"№",
					"Grouping",
					"Beginning",
					"End",
					"Duration",
					"Mileage"
				],
				"header_type":[
					"",
					"",
					"time_begin",
					"time_end",
					"duration",
					"mileage"
				]
			}
		],
		"attachments":[]
	}
}

Three key parameters from the response that are important for us here are as follows:

• tables — shows the number of tables in the report as an array. In this case, only one table (Trips) is mentioned, therefore its index will be 0.
• rows — the number of rows in the table, which is 2 in this case. Therefore, their indexes range from 0 to 1. This refers only to the rows at the top level of nesting, there may be more inside.
• level — the number of levels of nesting, which is 3 in this case, as there is grouping in the report. Therefore, there are levels with indexes from 0 to 2 in the table.

Other parameters from the response can also be briefly listed. The columns parameter indicates the number of columns, and their names are described in the header parameter. A value of 0 for the msgsRendered parameter indicates that the report template doesn't display tracks on the map. Empty stats and attachments parameters indicate that there are no Statistics nor attachments (e.g., charts) in the report template.

6. Selecting Rows in a Multi-Level Table

Knowing the index of the table content, let’s display it using the request report/select_result_rows.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/select_result_rows¶ms={"tableIndex":0,"config":{"type":"range","data":{"from":0,"to":1,"level":2}}}&sid=SESSION_IDENTIFIER

[
	{
		"n":0,
		"i1":0,
		"i2":1188,
		"t1":1688144420,
		"t2":1688158739,
		"d":1,
		"c":[
			"1",
			"June",
			{
				"t":"20:00:20",
				"v":1688144420,
				"y":47.2941741943,
				"x":26.4906959534,
				"u":55555
			},
			{
				"t":"23:58:59",
				"v":1688158739,
				"y":43.1049079895,
				"x":25.6173667908,
				"u":55555
			},
			"3:53:36",
			"576.60 km"
		],
		"r":[
			{
				"n":0,
				"i1":0,
				"i2":1188,
				"t1":1688144420,
				"t2":1688158739,
				"d":2,
				"c":[
					"1.1",
					"2023-06-30",
					{
						"t":"20:00:20",
						"v":1688144420,
						"y":47.2941741943,
						"x":26.4906959534,
						"u":55555
					},
					{
						"t":"23:58:59",
						"v":1688158739,
						"y":43.1049079895,
						"x":25.6173667908,
						"u":55555
					},
					"3:53:36",
					"576.60 km"
				],
				"r":[
					{
						"n":0,
						"i1":0,
						"i2":790,
						"t1":1688144420,
						"t2":1688154878,
						"d":0,
						"c":[
							"1.1.1",
							"2023-06-30 20:00:20",
							{
								"t":"20:00:20",
								"v":1688144420,
								"y":47.2941741943,
								"x":26.4906959534,
								"u":55555
							},
							{
								"t":"22:54:38",
								"v":1688154878,
								"y":43.8697662354,
								"x":26.0177116394,
								"u":55555
							},
							"2:54:18",
							"469.54 km"
						]
					},
					{
						"n":1,
						"i1":936,
						"i2":1188,
						"t1":1688155181,
						"t2":1688158739,
						"d":0,
						"c":[
							"1.1.2",
							"2023-06-30 22:59:41",
							{
								"t":"22:59:41",
								"v":1688155181,
								"y":43.8698196411,
								"x":26.0177154541,
								"u":55555
							},
							{
								"t":"23:58:59",
								"v":1688158739,
								"y":43.1049079895,
								"x":25.6173667908,
								"u":55555
							},
							"0:59:18",
							"107.06 km"
						]
					}
				]
			}
		]
	},
	{
		"n":1,
		"i1":1193,
		"i2":2910,
		"t1":1688158805,
		"t2":1688173175,
		"d":1,
		"c":[
			"2",
			"July",
				{
					"t":"00:00:05",
					"v":1688158805,
					"y":43.0983314514,
					"x":25.6316585541,
					"u":55555
				},
				{
					"t":"03:59:35",
					"v":1688173175,
					"y":41.5760040283,
					"x":26.9871864319,
					"u":55555
				},
				"3:41:42",
				"294.55 km"
		],
		"r":[
			{
				"n":0,
				"i1":1193,
				"i2":2910,
				"t1":1688158805,
				"t2":1688173175,
				"d":3,
				"c":[
					"2.1",
					"2023-07-01",
					{
						"t":"00:00:05",
						"v":1688158805,
						"y":43.0983314514,
						"x":25.6316585541,
						"u":55555
					},
					{
						"t":"03:59:35",
						"v":1688173175,
						"y":41.5760040283,
						"x":26.9871864319,
						"u":55555
					},
					"3:41:42",
					"294.55 km"
				],
				"r":[
					{
						"n":0,
						"i1":1193,
						"i2":2171,
						"t1":1688158805,
						"t2":1688169690,
						"d":0,
						"c":[
							"2.1.1",
							"2023-07-01 00:00:05",
							{
								"t":"00:00:05",
								"v":1688158805,
								"y":43.0983314514,
								"x":25.6316585541,
								"u":55555
							},
							{
								"t":"03:01:30",
								"v":1688169690,
								"y":41.7139854431,
								"x":26.3660545349,
								"u":55555
							},
							"3:01:25",
							"235.31 km"
						]
					},
					{
						"n":1,
						"i1":2340,
						"i2":2486,
						"t1":1688170034,
						"t2":1688170841,
						"d":0,
						"c":[
							"2.1.2",
							"2023-07-01 03:07:14",
							{
								"t":"03:07:14",
								"v":1688170034,
								"y":41.7140579224,
								"x":26.365901947,
								"u":55555
							},
							{
								"t":"03:20:41",
								"v":1688170841,
								"y":41.7122383118,
								"x":26.3712425232,
								"u":55555
							},
							"0:13:27",
							"1.39 km"
						]
					},
					{
						"n":2,
						"i1":2833,
						"i2":2910,
						"t1":1688171565,
						"t2":1688173175,
						"d":0,
						"c":[
							"2.1.3",
							"2023-07-01 03:32:45",
							{
								"t":"03:32:45",
								"v":1688171565,
								"y":41.7120819092,
								"x":26.3711204529,
								"u":55555
							},
							{
								"t":"03:59:35",
								"v":1688173175,
								"y":41.5760040283,
								"x":26.9871864319,
								"u":55555
							},
							"0:26:50",
							"57.84 km"
						]
					}
				]
			}
		]
	}
]

7. Export to File

Let’s export the result to a PDF file using the request report/export_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Grouped%20trips"}&sid=SESSION_IDENTIFIER

There is no response displayed for this API request, instead, the file download starts automatically.

8. Deleting the Result of the Previous Report

Use the request report/cleanup_result.

https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=SESSION_IDENTIFIER

{
	"error":0
}

A zero value indicates successful deletion.

Peculiarities of Obtaining Results

Obtaining data from tables can be performed using the requests report/get_result_rows or report/select_result_rows, which use the parameter tableIndex to access a table with a specific index. At the same time, it is necessary to take into account that when executing a report for different intervals, the index of the same table may change due to the presence or absence of other tables.

To better understand the situation, let's consider an example. Let’s suppose the report template includes tables for Trips, Fuel Fillings, and Geofences. When executing the report for the interval from July 1st to 3rd, the result will contain all tables, and therefore their indexes will have the following values:

0 — Trips
1 — Fuel Drains
2 — Geofences

At the same time, when executing the report for the interval from July 4th to 6th, the indexes of some tables will change due to the absence of registered fuel fillings and will take other values:

0 — Trips
1 — Geofences

In this example, it is clear that when executing the report for different intervals, the index of the Geofences table changes. Therefore, accessing the table with index 2 will not always display information about visiting geofences. To fix such situations, it is recommended to apply additional checks, for example, based on the table name or the names of its columns.

Ekaterina Grib,Customer Service Engineer 2023-08-31

This article contains answers to the most frequently asked questions about the Remote API.

Are there any limitations on API usage?

Global limitations are described in the documentation. Typically, reaching these limitations indicates that the developed application is not optimized for working with the API. For example, it makes multiple authorization requests instead of maintaining one active session.

There are also limitations on some requests, which are mentioned in the request description in the documentation. For example, only one report can be executed during a session at a time. If the session contains the results of the previous report execution, they should be deleted using the request report/cleanup_result before executing the next report. Additionally, the request to execute reports cannot be performed simultaneously with some other requests.

Is it possible to organize real-time data transfer from Wialon using the API?

No. API requests work on the request-response method. This means that data on the receiving side will not be updated without sending a request.

If it is necessary to receive data from hardware as soon as new messages arrive, retranslators can be used.

How to create a locator using the API?

Let's consider an example: it is necessary to create a locator with infinite lifespan, which will display units with system IDs 11111111 and 22222222, as well as geofences from a resource with system ID 12345678, but will not display units’ tracks.

To do this, you need to use the request token/update:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update¶ms=
{"callMode":"create","app":"locator","at":0,"dur":0,"fl":256,"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}","items":[11111111,22222222,12345678]}&sid=SESSION_IDENTIFIER

The response to the request will include the parameter h containing the token value. To obtain the desired link, the token value should be inserted into the following link: https://hosting.wialon.com/locator/index.html?t=TOKEN_VALUE

How to obtain a token with maximum access and infinite lifespan?

If token creation is done through an extended form, it is necessary to use the parameters access_type=-1 and duration=0. For example:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

If token creation is done through the request token/update, it is necessary to use the parameters fl=-1 and dur=0. For example:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update¶ms=
{"callMode":"create","app":"Wialon Hosting","at":0,"dur":0,"fl":-1,"p":"{}"}&sid=SESSION_IDENTIFIER

Why can an error with code 1 be returned when using an unlimited token?

An error with code 1 indicates that the current session is invalid. The token's lifespan is not directly related to the session.

To fix the situation, it is necessary to perform authorization again. The response to the token login contains the parameter eid, and its value is the unique session identifier. It will be used in almost all API requests.

How to fix an error with code 4?

An error with code 4 corresponds to invalid input, which can mean:

• incorrect data type (numeric, text, etc.);
  

• incorrect parameter names;
  
• incorrect separators (commas, quotes, spaces, brackets, etc.);
• absence of encoding for transmission in the URL.

Let's consider an example of a request with all the mentioned errors:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":"2";"compres":0;"outputFileName":"List of trips"}&sid=SESSION_IDENTIFIER

In this example, the following errors were made:

1. The parameter format should contain a number, but since its value is enclosed in quotes, it is interpreted as text.
   
2. Instead of the parameter with the name compress, a parameter with the name compres was used.
3. A semicolon was used instead of a comma to separate the parameters.
4. The space character was not encoded for transmission in the URL.

The correct request will look like this:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"List%20of%20trips"}&sid=SESSION_IDENTIFIER

Why does an error with code 7 occur when using unique unit IDs?

API requests use internal system IDs of items, not unique unit IDs from the General tab. By default, these IDs are not displayed in web interfaces.

You can use the search items by property request (core/search_items) to obtain the system IDs of items. The desired value will be found in the parameter id of the response to this request.

Why is access to the unit restricted even though the user has full access rights?

The problem is likely due to insufficient rights of the token being used.

To check the rights of the token, perform the token login:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"TOKEN_VALUE"}

The response will contain the parameter fl, which displays the current rights of the token. To change them, edit the current token or create a new one.

How to get the last coordinates of units?

To obtain the last coordinates of multiple units, you can use the search items by property request (core/search_items). In this case, you need to specify access flags according to which the response will display unit names ("flag":1") and information about the last position of units ("flag":1024). Flags can be summed together, so the request will use the value 1 + 1024 = 1025.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1025,"from":0,"to":0}&sid=SESSION_IDENTIFIER

How to get a list of all units available to the user?

To display all units available to the user, you can use the search items by property request (core/search_items) with the value "propValueMask":"*".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

The response will return a list of units that are accessible to the user whose session identifier was used in the request.

How to get the names of groups to which a certain unit is added?

To get the names of groups that include a unit with the system ID 11112222, you need to use the search items by property request (core/search_items) with the values "itemsType":"avl_unit_group", "propName":"sys_units", and "propType":"list".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"sys_units","propValueMask":11112222,"sortType":"sys_name","propType":"list"},"force":1,"flags":1,"from":0,"to":0}}&sid=SESSION_IDENTIFIER

How to get the names of units from a certain group?

To get the names of units that are included in a group named Group, you need to use two search items by property requests (core/search_items): the first one will search for the unit group (avl_unit_group), and the second one will search for the unit (avl_unit).

1. First, you need to get a list of system IDs of units that belong to the group (specify its name in the parameter propValueMask):

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"sys_name","propValueMask":"Group","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

    Response

   {
   	"searchSpec":{
   		"itemsType":"avl_unit_group",
   		"propName":"sys_name",
   		"propValueMask":"Group",
   		"sortType":"sys_name",
   		"propType":"",
   		"or_logic":"0"
   	},
   	"dataFlags":1,
   	"totalItemsCount":1,
   	"indexFrom":0,
   	"indexTo":0,
   	"items":[
   		{
   			"nm":"Group",
   			"cls":5,
   			"id":10000000,
   			"mu":0,
   			"u":[
   				20000001,
   				20000002,
   				20000003
   			],
   			"uacl":-1
   		}
   	]
   }
   

2. In the response to the previous request, you need to find the parameter u with the system IDs of units. You should substitute them in the parameter propValueMask for the next search request:
   

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_id","propValueMask":"20000001,20000002,20000003","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

    Response

   {
   	searchSpec:{
   		itemsType:"avl_unit",
   		propName:"sys_id",
   		propValueMask:"20000001,20000002,20000003",
   		sortType:"sys_name",
   		propType:"",
   		or_logic:"0"
   	},
   	dataFlags:1,
   	totalItemsCount:3,
   	indexFrom:0,
   	indexTo:0,
   	items:[
   		{
   			nm:"Unit_1",
   			cls:2,
   			id:20000001,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_2",
   			cls:2,
   			id:20000002,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_3",
   			cls:2,
   			id:20000003,
   			mu:0,
   			uacl:-1
   		}
   	]
   }
   

   The names of units will be displayed in the parameters nm.

Why do the results of the report differ between the interface and the response to the API request?

When executing reports through API requests, it is important not to forget to set the time zone for the current session. To do this, immediately after authorization, you should apply the user's localization settings once.

Ekaterina Grib,Customer Service Engineer 2023-09-01